<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Update : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Update
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Update</h1>

<p>If you want to update multiple objects or rows at the same time, you can do that easily using the <var><u>update</u></var> method.
   This method accepts one or more field-value pairs, and can use many of the existing DataMapper functions to determine which columns to update.</p>

<div class="important">
	<p>Be careful with this method.  Without having limited it with <var><u>where</u></var> statements or similar methods it will modify <strong>every single row on the table</strong>!</p>
	<p>Also, this method <strong>bypasses validation</strong>, and can also operate on in-table foreign keys, so please be aware of the risks.</p>
</div>

<h2>Basic Updates</h2>
<h3>Set a Field in Every Row to the Same Value</h3>
<p>The simplest form of <var><u>update</u></var> is to update every single row in a table at once.</p>
<pre>
<samp>// Mark all users as new
</samp><var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$success </var><kbd>= </kbd><var>$user</var><kbd>-&gt;</kbd><var><u>update</u></var><kbd>(</kbd><dfn>'isnew'</dfn><kbd>, </kbd><var><dfn>TRUE</dfn></var><kbd>);</kbd>
</pre>

This generates SQL that looks like this:
<pre>
UPDATE `users`
SET `isnew` = TRUE
</pre>

<h3>Limiting Which Rows Are Updated</h3>
<p>You can limit which rows are updated by using any of the non-related methods listed on the <a href="get.html">Get</a> or <a href="getadvanced.html">Get (Advanced)</a> sections.</p>
<pre>
<samp>// Mark all users that have expired for deletion.
</samp><var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$year </var><kbd>= </kbd><var>365</var><kbd>*</kbd><var>24</var><kbd>*</kbd><var>60</var><kbd>*</kbd><var>60</var><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'last_accessed &lt;'</dfn><kbd>, </kbd><var><b>time</b></var><kbd>()-</kbd><var>$year</var><kbd>)-&gt;</kbd><var><u>update</u></var><kbd>(</kbd><dfn>'mark_for_deletion'</dfn><kbd>, </kbd><var><dfn>TRUE</dfn></var><kbd>);</kbd>
</pre>


<h2>Updating Multiple Columns</h2>
<p>You can pass an array in as the first parameter if you need to update more than one column at a time.</p>
<pre>
<samp>// Reset Changes
</samp><var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$user</var><kbd>-&gt;</kbd><var><u>update</u></var><kbd>(array(</kbd><dfn>'mark_for_deletion' </dfn><kbd>=&gt; </kbd><var><dfn>FALSE</dfn></var><kbd>, </kbd><dfn>'isnew' </dfn><kbd>=&gt; </kbd><var><dfn>FALSE</dfn></var><kbd>));</kbd>
</pre>

<h2>Using Formulas in Updates</h2>
<p>The <var><u>update</u></var> method accepts a third parameter that, when <dfn>FALSE</dfn>, allows you to specify formulas.</p>
<pre>
<samp>// Added a new column, set it to the all upper-case version of the user's name.
</samp><var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$user</var><kbd>-&gt;</kbd><var><u>update</u></var><kbd>(</kbd><dfn>'ucase_name'</dfn><kbd>, </kbd><dfn>'UPPER(name)'</dfn><kbd>, </kbd><var><dfn>FALSE</dfn></var><kbd>);</kbd>
</pre>

<h3>Using formulas with multiple columns</h3>
<p>You can also use formulas with multiple columns, just pass <dfn>FALSE</dfn> as the second parameter.</p>
<pre>
<var>$pet </var><kbd>= new </kbd><var>VirtualPet</var><kbd>();
</kbd><var>$pet</var><kbd>-&gt;</kbd><var><u>update</u></var><kbd>(array(</kbd><dfn>'hunger' </dfn><kbd>=&gt; </kbd><dfn>'hunger + 1'</dfn><kbd>, </kbd><dfn>'tiredness' </dfn><kbd>=&gt; </kbd><dfn>'tiredness + 1'</dfn><kbd>), </kbd><var><dfn>FALSE</dfn></var><kbd>);</kbd>
</pre>

<p class="note">
	Datamapper ORM will attempt to add the table name to values when using formulas.
	The table name is only added when the value is in the form <dfn>"field ..."</dfn>, where <var>field</var> is a field on the table, and <var>...</var> is anything.
	The space is required.  In the example above, the value would become <var>virtualpets.hunger + 1</var>.  The identifiers are <strong>not</strong> protected.
</p>

<h2>Getting the Number of Affected Rows</h2>
<p>Datamapper ORM does not provide any method to find the number of affected rows.  However, you can access it directly using the <a href="http://codeigniter.com/user_guide/database/helpers.html">existing CodeIgniter method</a>:</p>
<pre>
<var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$year </var><kbd>= </kbd><var>365</var><kbd>*</kbd><var>24</var><kbd>*</kbd><var>60</var><kbd>*</kbd><var>60</var><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'last_accessed &lt;'</dfn><kbd>, </kbd><var><b>time</b></var><kbd>()-</kbd><var>$year</var><kbd>)-&gt;</kbd><var><u>update</u></var><kbd>(</kbd><dfn>'mark_for_deletion'</dfn><kbd>, </kbd><var><dfn>TRUE</dfn></var><kbd>);
</kbd><var>$affected </var><kbd>= </kbd><var>$user</var><kbd>-&gt;</kbd><var>db</var><kbd>-&gt;</kbd><var>affected_rows</var><kbd>();
echo(</kbd><dfn>"</dfn><var>$affected</var><dfn> user accounts were marked for deletion."</dfn><kbd>);</kbd>
</pre>
<p>Please note that not all databases support this feature on all methods.</p>

<h1>Update All</h1>
<p>Because CodeIgniter's AcitveRecord methods do not allow for joins within UPDATE queries, it is not possible to simply update related items.</p>
<p>
	To help with this, there's an additonal method called <var><u>update_all</u></var>, which will use the ids of the objects in the all array.
 	Use it like this:
</p>
<pre>
<var>$group </var><kbd>= new </kbd><var>Group</var><kbd>();
</kbd><var>$group</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Administrators'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();
</kbd><samp>// You only need to select the ID column, however the select() is optional.
</samp><var>$group</var><kbd>-&gt;</kbd><var>user</var><kbd>-&gt;</kbd><var><u>select</u></var><kbd>(</kbd><dfn>'id'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();
</kbd><var>$group</var><kbd>-&gt;</kbd><var>user</var><kbd>-&gt;</kbd><var><u>update_all</u></var><kbd>(</kbd><dfn>'is_all_powerful'</dfn><kbd>, </kbd><var><dfn>TRUE</dfn></var><kbd>);</kbd>
</pre>

<p>You can use any set of objects for this method.  It uses <var><u>where_in</u></var> on the backside to filter the results.</p>


</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
